---
title: エージェントの実行
description: Configure and execute agent workflows with the Runner class
---

import { Aside, Code } from '@astrojs/starlight/components';
import helloWorldWithRunnerExample from '../../../../../../examples/docs/hello-world-with-runner.ts?raw';
import helloWorldExample from '../../../../../../examples/docs/hello-world.ts?raw';
import runningAgentsExceptionExample from '../../../../../../examples/docs/running-agents/exceptions1.ts?raw';
import chatLoopExample from '../../../../../../examples/docs/running-agents/chatLoop.ts?raw';
import conversationIdExample from '../../../../../../examples/docs/running-agents/conversationId.ts?raw';
import previousResponseIdExample from '../../../../../../examples/docs/running-agents/previousResponseId.ts?raw';

エージェントはそれ自体では何もしません。`Runner` クラスまたは `run()` ユーティリティで **run** します。

<Code lang="typescript" code={helloWorldExample} title="Simple run" />

カスタム Runner が不要な場合は、シングルトンのデフォルト `Runner` インスタンスを実行する `run()` ユーティリティも使えます。

または、独自の Runner インスタンスを作成できます。

<Code lang="typescript" code={helloWorldWithRunnerExample} title="Simple run" />

エージェントを実行すると、最終出力と実行の全履歴を含む [エージェントの実行結果](/openai-agents-js/ja/guides/results) オブジェクトを受け取ります。

## エージェントループ

Runner の run メソッドを使うとき、開始するエージェントと入力を渡します。入力は文字列（ユーザーのメッセージとみなされます）か、OpenAI Responses API のアイテムである入力アイテムのリストのいずれかです。

Runner は次のループを実行します。

1. 現在の入力で現在のエージェントのモデルを呼び出す
2. LLM のレスポンスを検査する
   - **Final output** → 返す
   - **Handoff** → 新しいエージェントに切り替え、蓄積された会話履歴を保持し、1 に戻る
   - **Tool calls** → ツールを実行し、その結果を会話に追加して 1 に戻る
3. `maxTurns` に達したら [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスローする

<Aside type="note">
  LLM
  の出力が「最終出力」と見なされるルールは、望まれる型のテキスト出力を生成し、ツール呼び出しがないことです。
</Aside>

### Runner のライフサイクル

アプリ起動時に `Runner` を作成し、リクエスト間で再利用します。このインスタンスはモデルプロバイダーやトレーシング設定などのグローバル設定を保持します。完全に異なるセットアップが必要な場合のみ別の `Runner` を作成してください。簡単なスクリプトでは内部でデフォルト Runner を使う `run()` を呼ぶこともできます。

## 実行引数

`run()` メソッドへの入力は、実行を開始する初期エージェント、実行の入力、そして一連のオプションです。

入力は、文字列（ユーザーのメッセージとみなされます）、[input items](/openai-agents-js/openai/agents-core/type-aliases/agentinputitem) のリスト、または [人間の介入（HITL）](/openai-agents-js/ja/guides/human-in-the-loop) エージェントを構築している場合は [`RunState`](/openai-agents-js/openai/agents-core/classes/runstate) オブジェクトのいずれかです。

追加のオプションは次のとおりです。

| Option     | Default | Description                                                                                                                                       |
| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stream`   | `false` | `true` の場合、`StreamedRunResult` を返し、モデルから到着するイベントを逐次発行します                                                             |
| `context`  | –       | すべての tool / guardrail / handoff に転送されるコンテキストオブジェクト。詳しくは [コンテキスト管理](/openai-agents-js/ja/guides/context) を参照 |
| `maxTurns` | `10`    | セーフティ制限。到達すると [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) をスローします           |
| `signal`   | –       | キャンセル用の `AbortSignal`                                                                                                                      |

## ストリーミング

ストリーミングを使うと、LLM の実行中にストリーミングイベントも受け取れます。ストリームが開始されると、`StreamedRunResult` には実行に関する完全な情報が含まれ、新たに生成されたすべての出力も含まれます。`for await` ループでストリーミングイベントを反復処理できます。詳しくは [ストリーミング](/openai-agents-js/ja/guides/streaming) を参照してください。

## 実行設定

独自の `Runner` インスタンスを作成する場合、Runner を構成するために `RunConfig` オブジェクトを渡せます。

| Field                       | Type                  | Purpose                                                                              |
| --------------------------- | --------------------- | ------------------------------------------------------------------------------------ |
| `model`                     | `string \| Model`     | 実行中の **すべて** のエージェントに特定のモデルを強制します                         |
| `modelProvider`             | `ModelProvider`       | モデル名を解決します。デフォルトは OpenAI プロバイダーです                           |
| `modelSettings`             | `ModelSettings`       | エージェントごとの設定を上書きするグローバルなチューニングパラメーター               |
| `handoffInputFilter`        | `HandoffInputFilter`  | handoff を行う際に入力アイテムを変更します（handoff 自体がすでに定義していない場合） |
| `inputGuardrails`           | `InputGuardrail[]`    | 初期のユーザー入力に適用されるガードレール                                           |
| `outputGuardrails`          | `OutputGuardrail[]`   | 最終出力に適用されるガードレール                                                     |
| `tracingDisabled`           | `boolean`             | OpenAI のトレーシングを完全に無効化します                                            |
| `traceIncludeSensitiveData` | `boolean`             | スパンは発行しつつ、トレースから LLM/ツールの入力と出力を除外します                  |
| `workflowName`              | `string`              | Traces ダッシュボードに表示され、関連する実行をグルーピングするのに役立ちます        |
| `traceId` / `groupId`       | `string`              | SDK に生成させる代わりに、トレースまたはグループ ID を手動で指定します               |
| `traceMetadata`             | `Record<string, any>` | すべてのスパンに付与する任意のメタデータ                                             |

## 会話 / チャットスレッド

`runner.run()`（または `run()` ユーティリティ）への各呼び出しは、アプリケーションレベルの会話における 1 回の **turn** を表します。エンドユーザーにどの程度の `RunResult` を表示するかは任意です。`finalOutput` のみの場合もあれば、生成されたすべてのアイテムを表示する場合もあります。

<Code lang="typescript" code={chatLoopExample} title="会話履歴を引き継ぐ例" />

インタラクティブ版は [チャットの code examples](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts) を参照してください。

### サーバー管理の会話

毎回ローカルの全文書を送らずに、OpenAI Responses API に会話履歴を保持させることができます。長い会話や複数サービスの調整に便利です。詳細は [Conversation state guide](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses) を参照してください。

OpenAI はサーバー側状態を再利用する 2 つの方法を提供します。

#### 1. 会話全体に対する `conversationId`

[Conversations API](https://platform.openai.com/docs/api-reference/conversations/create) で一度会話を作成し、その ID を各 turn で再利用できます。SDK は新たに生成されたアイテムのみを自動的に含めます。

<Code
  lang="typescript"
  code={conversationIdExample}
  title="サーバー会話の再利用"
/>

#### 2. 直前の turn から継続するための `previousResponseId`

最初から Responses API のみで始めたい場合、各リクエストを前回のレスポンスから返された ID で連結できます。これにより、完全な会話リソースを作成せずに turn をまたいでコンテキストを維持できます。

<Code
  lang="typescript"
  code={previousResponseIdExample}
  title="previousResponseId による連結"
/>

## 例外

SDK は捕捉可能な少数のエラーをスローします。

- [`MaxTurnsExceededError`](/openai-agents-js/openai/agents-core/classes/maxturnsexceedederror) – `maxTurns` に到達
- [`ModelBehaviorError`](/openai-agents-js/openai/agents-core/classes/modelbehaviorerror) – モデルが無効な出力を生成（例: 不正な JSON、未知のツール）
- [`InputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/inputguardrailtripwiretriggered) / [`OutputGuardrailTripwireTriggered`](/openai-agents-js/openai/agents-core/classes/outputguardrailtripwiretriggered) – ガードレール違反
- [`GuardrailExecutionError`](/openai-agents-js/openai/agents-core/classes/guardrailexecutionerror) – ガードレールが完了に失敗
- [`ToolCallError`](/openai-agents-js/openai/agents-core/classes/toolcallerror) – 関数ツール呼び出しのいずれかが失敗
- [`UserError`](/openai-agents-js/openai/agents-core/classes/usererror) – 設定またはユーザー入力に基づいてスローされたエラー

すべて基底の `AgentsError` クラスを継承しており、現在の実行状態にアクセスするための `state` プロパティを提供することがあります。

以下は `GuardrailExecutionError` を処理するサンプルコードです。

<Code
  lang="typescript"
  code={runningAgentsExceptionExample}
  title="Guardrail execution error"
/>

上記の例を実行すると、次の出力が表示されます。

```
Guardrail execution failed: Error: Input guardrail failed to complete: Error: Something is wrong!
Math homework guardrail tripped
```

---

## 次のステップ

- [モデル](/openai-agents-js/ja/guides/models) の設定方法を学ぶ
- エージェントに [ツール](/openai-agents-js/ja/guides/tools) を提供する
- 本番運用に向けて [ガードレール](/openai-agents-js/ja/guides/guardrails) や [トレーシング](/openai-agents-js/ja/guides/tracing) を追加する
